LOCAL MOSAIC 2.3  -  photo mosaics made entirely on your Mac
=============================================================

Pick one "master" picture and a folder of photos. Local Mosaic rebuilds the
master picture out of the small photos: a high-resolution photo mosaic. Faces
are detected so each small photo is cropped around people, repeats are spread
apart, and the portrait is blended over the tiles so it stays recognisable.
Nothing is uploaded anywhere. Works on Apple Silicon and Intel Macs,
macOS 12 or newer.


ONE-TIME SETUP (about 2 minutes)
--------------------------------
The app does its rendering with Python, which Apple ships with macOS, plus
three free image libraries. Open Terminal (Applications > Utilities) and paste:

    xcode-select --install

(Skip if it says the tools are already installed.) Then paste:

    /usr/bin/python3 -m pip install --user pillow numpy opencv-python

That exact "/usr/bin/python3" matters: it is the Python the app calls. If you
only have another Python (Homebrew, python.org), the app will not see the
libraries.


OPENING THE APP THE FIRST TIME
------------------------------
Local Mosaic is a small free app that is not registered with Apple, so macOS
shows a warning the first time. Move "Local Mosaic.app" to your Applications
folder, then:

  macOS 15 Sequoia and newer:
    1. Double-click the app. Click "Done" on the warning.
    2. Open System Settings > Privacy & Security, scroll down, and click
       "Open Anyway" next to Local Mosaic. Confirm.

  macOS 12 to 14:
    1. Right-click (or Control-click) the app and choose "Open".
    2. Click "Open" in the dialog.

  If macOS says the app "is damaged and can't be opened", paste this in
  Terminal and try again:

    xattr -dr com.apple.quarantine "/Applications/Local Mosaic.app"

After the first time it opens normally.


MAKING A MOSAIC
---------------
1. Master image: choose the big picture the mosaic should look like.
   Portraits of one or two people work best.
2. Photo library: choose a folder of photos. 200 to 1,000 photos is a good
   range; the app refuses nothing, but fewer than ~100 means obvious repeats.
3. Finished mosaic: choose where to save the result (a .jpg or .png).
4. Rendering style:
     "Mosaically-style"  - the whole picture is built from tiles (default).
     "Isolated people"   - removes the master's background on-device and
                           builds only the people from tiles.
5. Individual photo size: left = fewer, larger photos; right = more, smaller.
   (Default 52 across.)
6. Portrait clarity: higher makes faces and edges sharper. (Default 40%.)
7. Click "Create Mosaic". A 4000-pixel mosaic takes about a minute.


COMMAND LINE (optional)
-----------------------
The engine is one Python script you can run without the app:

    /usr/bin/python3 "Local Mosaic.app/Contents/Resources/mosaic.py" \
        master.jpg photos-folder out.jpg --columns 52 --overlay 0.40

    Run it with --help to see every option (tint, spacing, max reuse,
    tile visibility, --isolate-people with --mask-tool, JPEG quality).


BUILDING IT YOURSELF (optional)
-------------------------------
The "source" folder holds everything: LocalMosaic.m (the window),
SubjectMask.m (on-device person segmentation using Apple's Vision framework),
mosaic.py (the engine) and build.sh. With Xcode Command Line Tools installed,
run:   sh source/build.sh


Made by Moshe Orbach  -  https://mosheorbach.com
